1. The Quake-C Language

This is a very crude manual of Quake-C. It is rather incomplete.

1.1 Comments, names and types

Comments

Those comments are the same as in C++ (and many C languages).

Names

Names of variable, fields, or functions have a maximum of 64 characters, must begin with A-Z,a-z, or _, and can continue with those characters or 0-9.

Definition of new types

Let's start with the bad news: it is impossible, in Quake-C, to define new types. That means for instance that you cannot create a type named ammo, derived from float, that will only be used to store ammo count. So much for the clean programming habits.

Definition of structures and objects

It is often convenient, in C (or C++), to create new structures (or Objects, or record) to store a few related informations at the same place. For instance, you may wish to use a single structure to store all the ammo count of the player, and also the current selected weapon, since those informations are obviously related to each other.

Though both entity and vector are obviously structured types, it is impossible to create new structured types of that kind, in Quake-C. However, the entity type can be modifiedto suit some of your needs.

1.2 Constants and variables

Definition of variables

The general form of variable definitions is: 

    type variable1, variable2;
where type is one of the pre-defined simple types.

Scoping of variables: There are two levels of scoping. By default all variables are global: they can be accessed by any functions, and they are shared by all the functions (and all the clients of a given network server, of course).

But inside the functions, using the keyword local just before the declaration of a variable, you can make this variable visible only the the function itself (i.e. it will be allocated on the stack).

Note that parameters of a functions are treated like local variables, they are only visible to the function, but they can be modified.

Definitions of constants

Any global variable that is initialised by setting a value to it is actually assumed to be a constant.

The general form of definition of constants is then: 

    type variable1 = value;

Note that though it looks like a definition of variable, with a default initial value, is is totally different. There is no memory reserved for constants, and they are not saved to game files (only regular variables are).

To make matters worse, if you use a constant like a variable, and try to affect a new value to it... well, it's very likely that you will cause troubles to the program (malfunctions, or crashes). So never modify the value of a constant.

1.3 Operations

Logical operations

     !   // logical not
     &&  // logical and
     ||  // logical or

Take care that in if() conditional expressions containing two or more logical clauses, all the clauses will be evaluated before the condition test (like in Basic, and unlike C).

That means that if one part of your condition is not always valid or defined, you had better decompose your if() into two successive if(). It should also make it faster.

Comparisons

     <=    <      >=     >  
     ==  // equal, beware at the double = like in C.
     !=  // not equal, like in C.

Operations on floats or integer

     *  /  -  +
Use parenthesis to remove ambiguities.

Those operators perform bitwise operations on integers: 

    &   // bitwise and
    |   // bitwise or
These operators treat floats like integers, so they are usually meant to be used with values made of bit masks.

1.4 Definition of Functions

Ordinary functions

The general structure of a function definition is: 

    type (type param1, typeparam2, ... ) function =
    {
       ... code ...
       return expression;
    };
Notes:

Here are some examples: 

    void ()	think = {...};
    entity ()	FindTarget = {...};
    void(vector destination, float speed, void() callback)  SUB_CalcMove = {...};

Function calls

Here is how a function is called in Quake-C: 

    function_name ( parameter1, parameter2,... )
The cannot be more than 8 parameters.

Function declaration

If you want to use a function before defining it, you must declare it, otherwise the Quake-C compiler will not be able to use it.

The general structure of a function declaration is: 

    type (type param1, typeparam2, ... ) function;

Definition of a frame function

Frame functions (also called States) are special functions that are meant to facilitate the definition of models animation frames.

Here is an example: 

    void() framename = [$framenum, nextthink] { ...code...};
It is strictly equivalent to: 
    void() framename =
    {
       self.frame= $framenum;  // the model frame to displayed
       self.nextthink = time + 0.1;   // next frame happens in 1/10 of second
       self.think = nextthink; // the function to call at the next frame
       ...code...
    };

1.5 Loops and conditions

Conditional construct

    if( expression )
    {
      statements
    }
    else
    {
      statements
    }

Loop construct

    while( expression )
    {
      statements
    }
or 
    do
    { 
      statements
    }while( expression )